Crate kube

source ·
Expand description

Kube is an umbrella-crate for interacting with Kubernetes in Rust.

§Overview

Kube contains a Kubernetes client, a controller runtime, a custom resource derive, and various tooling required for building applications or controllers that interact with Kubernetes.

The main modules are:

You can use each of these as you need with the help of the exported features.

§Using the Client

use futures::{StreamExt, TryStreamExt};
use kube::{Client, api::{Api, ResourceExt, ListParams, PostParams}};
use k8s_openapi::api::core::v1::Pod;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Infer the runtime environment and try to create a Kubernetes Client
    let client = Client::try_default().await?;

    // Read pods in the configured namespace into the typed interface from k8s-openapi
    let pods: Api<Pod> = Api::default_namespaced(client);
    for p in pods.list(&ListParams::default()).await? {
        println!("found pod {}", p.name_any());
    }
    Ok(())
}

For details, see:

  • Client for the extensible Kubernetes client
  • Api for the generic api methods available on Kubernetes resources
  • k8s-openapi for documentation about the generated Kubernetes types

§Using the Runtime with the Derive macro

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::json;
use futures::{StreamExt, TryStreamExt};
use k8s_openapi::apiextensions_apiserver::pkg::apis::apiextensions::v1::CustomResourceDefinition;
use kube::{
    api::{Api, DeleteParams, PatchParams, Patch, ResourceExt},
    core::CustomResourceExt,
    Client, CustomResource,
    runtime::{watcher, WatchStreamExt, wait::{conditions, await_condition}},
};

// Our custom resource
#[derive(CustomResource, Deserialize, Serialize, Clone, Debug, JsonSchema)]
#[kube(group = "clux.dev", version = "v1", kind = "Foo", namespaced)]
pub struct FooSpec {
    info: String,
    #[schemars(length(min = 3))]
    name: String,
    replicas: i32,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::try_default().await?;
    let crds: Api<CustomResourceDefinition> = Api::all(client.clone());

    // Apply the CRD so users can create Foo instances in Kubernetes
    crds.patch("foos.clux.dev",
        &PatchParams::apply("my_manager"),
        &Patch::Apply(Foo::crd())
    ).await?;

    // Wait for the CRD to be ready
    tokio::time::timeout(
        std::time::Duration::from_secs(10),
        await_condition(crds, "foos.clux.dev", conditions::is_crd_established())
    ).await?;

    // Watch for changes to foos in the configured namespace
    let foos: Api<Foo> = Api::default_namespaced(client.clone());
    let wc = watcher::Config::default();
    let mut apply_stream = watcher(foos, wc).applied_objects().boxed();
    while let Some(f) = apply_stream.try_next().await? {
        println!("saw apply to {}", f.name_any());
    }
    Ok(())
}

For details, see:

  • CustomResource for documentation how to configure custom resources
  • runtime::watcher for how to long-running watches work and why you want to use this over Api::watch
  • runtime for abstractions that help with more complicated Kubernetes application

§Examples

A large list of complete, runnable examples with explainations are available in the examples folder.

Modules§

  • apiclient
    API helpers for structured interaction with the Kubernetes API
  • clientclient
    A basic API client for interacting with the Kubernetes API
  • configconfig
    Kubernetes configuration objects from ~/.kube/config, $KUBECONFIG, or the cluster environment.
  • Re-exports from kube_core Crate with types and traits necessary for interacting with the Kubernetes API
  • discoveryclient
    High-level utilities for runtime API discovery.
  • errorconfig or client
    Error handling and error types
  • runtimeruntime
    Re-exports from kube-runtime Common components for building Kubernetes operators

Structs§

  • Apiclient
    The generic Api abstraction
  • Clientclient
    Client for connecting with a Kubernetes cluster.
  • Configconfig
    Configuration object detailing things like cluster URL, default namespace, root certificates, and timeouts.
  • Discoveryclient
    A caching client for running API discovery against the Kubernetes API.

Enums§

Traits§

Type Aliases§

  • Resultconfig or client
    Convient alias for Result<T, Error>

Derive Macros§